home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / Kubuntu 8.10 / kubuntu-8.10-desktop-i386.iso / casper / filesystem.squashfs / usr / lib / ruby / 1.8 / fileutils.rb < prev    next >
Encoding:
Ruby Source  |  2007-03-04  |  42.0 KB  |  1,592 lines
  1. # 
  2. # = fileutils.rb
  3. # 
  4. # Copyright (c) 2000-2006 Minero Aoki
  5. # 
  6. # This program is free software.
  7. # You can distribute/modify this program under the same terms of ruby.
  8. # 
  9. # == module FileUtils
  10. # 
  11. # Namespace for several file utility methods for copying, moving, removing, etc.
  12. # 
  13. # === Module Functions
  14. # 
  15. #   cd(dir, options)
  16. #   cd(dir, options) {|dir| .... }
  17. #   pwd()
  18. #   mkdir(dir, options)
  19. #   mkdir(list, options)
  20. #   mkdir_p(dir, options)
  21. #   mkdir_p(list, options)
  22. #   rmdir(dir, options)
  23. #   rmdir(list, options)
  24. #   ln(old, new, options)
  25. #   ln(list, destdir, options)
  26. #   ln_s(old, new, options)
  27. #   ln_s(list, destdir, options)
  28. #   ln_sf(src, dest, options)
  29. #   cp(src, dest, options)
  30. #   cp(list, dir, options)
  31. #   cp_r(src, dest, options)
  32. #   cp_r(list, dir, options)
  33. #   mv(src, dest, options)
  34. #   mv(list, dir, options)
  35. #   rm(list, options)
  36. #   rm_r(list, options)
  37. #   rm_rf(list, options)
  38. #   install(src, dest, mode = <src's>, options)
  39. #   chmod(mode, list, options)
  40. #   chmod_R(mode, list, options)
  41. #   chown(user, group, list, options)
  42. #   chown_R(user, group, list, options)
  43. #   touch(list, options)
  44. #
  45. # The <tt>options</tt> parameter is a hash of options, taken from the list
  46. # <tt>:force</tt>, <tt>:noop</tt>, <tt>:preserve</tt>, and <tt>:verbose</tt>.
  47. # <tt>:noop</tt> means that no changes are made.  The other two are obvious.
  48. # Each method documents the options that it honours.
  49. #
  50. # All methods that have the concept of a "source" file or directory can take
  51. # either one file or a list of files in that argument.  See the method
  52. # documentation for examples.
  53. #
  54. # There are some `low level' methods, which do not accept any option:
  55. #
  56. #   copy_entry(src, dest, preserve = false, dereference = false)
  57. #   copy_file(src, dest, preserve = false, dereference = true)
  58. #   copy_stream(srcstream, deststream)
  59. #   remove_entry(path, force = false)
  60. #   remove_entry_secure(path, force = false)
  61. #   remove_file(path, force = false)
  62. #   compare_file(path_a, path_b)
  63. #   compare_stream(stream_a, stream_b)
  64. #   uptodate?(file, cmp_list)
  65. #
  66. # == module FileUtils::Verbose
  67. # 
  68. # This module has all methods of FileUtils module, but it outputs messages
  69. # before acting.  This equates to passing the <tt>:verbose</tt> flag to methods
  70. # in FileUtils.
  71. # 
  72. # == module FileUtils::NoWrite
  73. # 
  74. # This module has all methods of FileUtils module, but never changes
  75. # files/directories.  This equates to passing the <tt>:noop</tt> flag to methods
  76. # in FileUtils.
  77. # 
  78. # == module FileUtils::DryRun
  79. # 
  80. # This module has all methods of FileUtils module, but never changes
  81. # files/directories.  This equates to passing the <tt>:noop</tt> and
  82. # <tt>:verbose</tt> flags to methods in FileUtils.
  83. # 
  84.  
  85. module FileUtils
  86.  
  87.   def self.private_module_function(name)   #:nodoc:
  88.     module_function name
  89.     private_class_method name
  90.   end
  91.  
  92.   # This hash table holds command options.
  93.   OPT_TABLE = {}   #:nodoc: internal use only
  94.  
  95.   #
  96.   # Options: (none)
  97.   #
  98.   # Returns the name of the current directory.
  99.   #
  100.   def pwd
  101.     Dir.pwd
  102.   end
  103.   module_function :pwd
  104.  
  105.   alias getwd pwd
  106.   module_function :getwd
  107.  
  108.   #
  109.   # Options: verbose
  110.   # 
  111.   # Changes the current directory to the directory +dir+.
  112.   # 
  113.   # If this method is called with block, resumes to the old
  114.   # working directory after the block execution finished.
  115.   # 
  116.   #   FileUtils.cd('/', :verbose => true)   # chdir and report it
  117.   # 
  118.   def cd(dir, options = {}, &block) # :yield: dir
  119.     fu_check_options options, OPT_TABLE['cd']
  120.     fu_output_message "cd #{dir}" if options[:verbose]
  121.     Dir.chdir(dir, &block)
  122.     fu_output_message 'cd -' if options[:verbose] and block
  123.   end
  124.   module_function :cd
  125.  
  126.   alias chdir cd
  127.   module_function :chdir
  128.  
  129.   OPT_TABLE['cd']    =
  130.   OPT_TABLE['chdir'] = [:verbose]
  131.  
  132.   #
  133.   # Options: (none)
  134.   # 
  135.   # Returns true if +newer+ is newer than all +old_list+.
  136.   # Non-existent files are older than any file.
  137.   # 
  138.   #   FileUtils.uptodate?('hello.o', %w(hello.c hello.h)) or \
  139.   #       system 'make hello.o'
  140.   # 
  141.   def uptodate?(new, old_list, options = nil)
  142.     raise ArgumentError, 'uptodate? does not accept any option' if options
  143.  
  144.     return false unless File.exist?(new)
  145.     new_time = File.mtime(new)
  146.     old_list.each do |old|
  147.       if File.exist?(old)
  148.         return false unless new_time > File.mtime(old)
  149.       end
  150.     end
  151.     true
  152.   end
  153.   module_function :uptodate?
  154.  
  155.   #
  156.   # Options: mode noop verbose
  157.   # 
  158.   # Creates one or more directories.
  159.   # 
  160.   #   FileUtils.mkdir 'test'
  161.   #   FileUtils.mkdir %w( tmp data )
  162.   #   FileUtils.mkdir 'notexist', :noop => true  # Does not really create.
  163.   #   FileUtils.mkdir 'tmp', :mode => 0700
  164.   # 
  165.   def mkdir(list, options = {})
  166.     fu_check_options options, OPT_TABLE['mkdir']
  167.     list = fu_list(list)
  168.     fu_output_message "mkdir #{options[:mode] ? ('-m %03o ' % options[:mode]) : ''}#{list.join ' '}" if options[:verbose]
  169.     return if options[:noop]
  170.  
  171.     list.each do |dir|
  172.       fu_mkdir dir, options[:mode]
  173.     end
  174.   end
  175.   module_function :mkdir
  176.  
  177.   OPT_TABLE['mkdir'] = [:mode, :noop, :verbose]
  178.  
  179.   #
  180.   # Options: mode noop verbose
  181.   # 
  182.   # Creates a directory and all its parent directories.
  183.   # For example,
  184.   # 
  185.   #   FileUtils.mkdir_p '/usr/local/lib/ruby'
  186.   # 
  187.   # causes to make following directories, if it does not exist.
  188.   #     * /usr
  189.   #     * /usr/local
  190.   #     * /usr/local/lib
  191.   #     * /usr/local/lib/ruby
  192.   #
  193.   # You can pass several directories at a time in a list.
  194.   # 
  195.   def mkdir_p(list, options = {})
  196.     fu_check_options options, OPT_TABLE['mkdir_p']
  197.     list = fu_list(list)
  198.     fu_output_message "mkdir -p #{options[:mode] ? ('-m %03o ' % options[:mode]) : ''}#{list.join ' '}" if options[:verbose]
  199.     return *list if options[:noop]
  200.  
  201.     list.map {|path| path.sub(%r</\z>, '') }.each do |path|
  202.       # optimize for the most common case
  203.       begin
  204.         fu_mkdir path, options[:mode]
  205.         next
  206.       rescue SystemCallError
  207.         next if File.directory?(path)
  208.       end
  209.  
  210.       stack = []
  211.       until path == stack.last   # dirname("/")=="/", dirname("C:/")=="C:/"
  212.         stack.push path
  213.         path = File.dirname(path)
  214.       end
  215.       stack.reverse_each do |path|
  216.         begin
  217.           fu_mkdir path, options[:mode]
  218.         rescue SystemCallError => err
  219.           raise unless File.directory?(path)
  220.         end
  221.       end
  222.     end
  223.  
  224.     return *list
  225.   end
  226.   module_function :mkdir_p
  227.  
  228.   alias mkpath    mkdir_p
  229.   alias makedirs  mkdir_p
  230.   module_function :mkpath
  231.   module_function :makedirs
  232.  
  233.   OPT_TABLE['mkdir_p']  =
  234.   OPT_TABLE['mkpath']   =
  235.   OPT_TABLE['makedirs'] = [:mode, :noop, :verbose]
  236.  
  237.   def fu_mkdir(path, mode)   #:nodoc:
  238.     path = path.sub(%r</\z>, '')
  239.     if mode
  240.       Dir.mkdir path, mode
  241.       File.chmod mode, path
  242.     else
  243.       Dir.mkdir path
  244.     end
  245.   end
  246.   private_module_function :fu_mkdir
  247.  
  248.   #
  249.   # Options: noop, verbose
  250.   # 
  251.   # Removes one or more directories.
  252.   # 
  253.   #   FileUtils.rmdir 'somedir'
  254.   #   FileUtils.rmdir %w(somedir anydir otherdir)
  255.   #   # Does not really remove directory; outputs message.
  256.   #   FileUtils.rmdir 'somedir', :verbose => true, :noop => true
  257.   # 
  258.   def rmdir(list, options = {})
  259.     fu_check_options options, OPT_TABLE['rmdir']
  260.     list = fu_list(list)
  261.     fu_output_message "rmdir #{list.join ' '}" if options[:verbose]
  262.     return if options[:noop]
  263.     list.each do |dir|
  264.       Dir.rmdir dir.sub(%r</\z>, '')
  265.     end
  266.   end
  267.   module_function :rmdir
  268.  
  269.   OPT_TABLE['rmdir'] = [:noop, :verbose]
  270.  
  271.   #
  272.   # Options: force noop verbose
  273.   #
  274.   # <b><tt>ln(old, new, options = {})</tt></b>
  275.   #
  276.   # Creates a hard link +new+ which points to +old+.
  277.   # If +new+ already exists and it is a directory, creates a link +new/old+.
  278.   # If +new+ already exists and it is not a directory, raises Errno::EEXIST.
  279.   # But if :force option is set, overwrite +new+.
  280.   # 
  281.   #   FileUtils.ln 'gcc', 'cc', :verbose => true
  282.   #   FileUtils.ln '/usr/bin/emacs21', '/usr/bin/emacs'
  283.   # 
  284.   # <b><tt>ln(list, destdir, options = {})</tt></b>
  285.   # 
  286.   # Creates several hard links in a directory, with each one pointing to the
  287.   # item in +list+.  If +destdir+ is not a directory, raises Errno::ENOTDIR.
  288.   # 
  289.   #   include FileUtils
  290.   #   cd '/sbin'
  291.   #   FileUtils.ln %w(cp mv mkdir), '/bin'   # Now /sbin/cp and /bin/cp are linked.
  292.   # 
  293.   def ln(src, dest, options = {})
  294.     fu_check_options options, OPT_TABLE['ln']
  295.     fu_output_message "ln#{options[:force] ? ' -f' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
  296.     return if options[:noop]
  297.     fu_each_src_dest0(src, dest) do |s,d|
  298.       remove_file d, true if options[:force]
  299.       File.link s, d
  300.     end
  301.   end
  302.   module_function :ln
  303.  
  304.   alias link ln
  305.   module_function :link
  306.  
  307.   OPT_TABLE['ln']   =
  308.   OPT_TABLE['link'] = [:force, :noop, :verbose]
  309.  
  310.   #
  311.   # Options: force noop verbose
  312.   #
  313.   # <b><tt>ln_s(old, new, options = {})</tt></b>
  314.   # 
  315.   # Creates a symbolic link +new+ which points to +old+.  If +new+ already
  316.   # exists and it is a directory, creates a symbolic link +new/old+.  If +new+
  317.   # already exists and it is not a directory, raises Errno::EEXIST.  But if
  318.   # :force option is set, overwrite +new+.
  319.   # 
  320.   #   FileUtils.ln_s '/usr/bin/ruby', '/usr/local/bin/ruby'
  321.   #   FileUtils.ln_s 'verylongsourcefilename.c', 'c', :force => true
  322.   # 
  323.   # <b><tt>ln_s(list, destdir, options = {})</tt></b>
  324.   # 
  325.   # Creates several symbolic links in a directory, with each one pointing to the
  326.   # item in +list+.  If +destdir+ is not a directory, raises Errno::ENOTDIR.
  327.   #
  328.   # If +destdir+ is not a directory, raises Errno::ENOTDIR.
  329.   # 
  330.   #   FileUtils.ln_s Dir.glob('bin/*.rb'), '/home/aamine/bin'
  331.   # 
  332.   def ln_s(src, dest, options = {})
  333.     fu_check_options options, OPT_TABLE['ln_s']
  334.     fu_output_message "ln -s#{options[:force] ? 'f' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
  335.     return if options[:noop]
  336.     fu_each_src_dest0(src, dest) do |s,d|
  337.       remove_file d, true if options[:force]
  338.       File.symlink s, d
  339.     end
  340.   end
  341.   module_function :ln_s
  342.  
  343.   alias symlink ln_s
  344.   module_function :symlink
  345.  
  346.   OPT_TABLE['ln_s']    =
  347.   OPT_TABLE['symlink'] = [:force, :noop, :verbose]
  348.  
  349.   #
  350.   # Options: noop verbose
  351.   # 
  352.   # Same as
  353.   #   #ln_s(src, dest, :force)
  354.   # 
  355.   def ln_sf(src, dest, options = {})
  356.     fu_check_options options, OPT_TABLE['ln_sf']
  357.     options = options.dup
  358.     options[:force] = true
  359.     ln_s src, dest, options
  360.   end
  361.   module_function :ln_sf
  362.  
  363.   OPT_TABLE['ln_sf'] = [:noop, :verbose]
  364.  
  365.   #
  366.   # Options: preserve noop verbose
  367.   #
  368.   # Copies a file content +src+ to +dest+.  If +dest+ is a directory,
  369.   # copies +src+ to +dest/src+.
  370.   #
  371.   # If +src+ is a list of files, then +dest+ must be a directory.
  372.   #
  373.   #   FileUtils.cp 'eval.c', 'eval.c.org'
  374.   #   FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6'
  375.   #   FileUtils.cp %w(cgi.rb complex.rb date.rb), '/usr/lib/ruby/1.6', :verbose => true
  376.   #   FileUtils.cp 'symlink', 'dest'   # copy content, "dest" is not a symlink
  377.   # 
  378.   def cp(src, dest, options = {})
  379.     fu_check_options options, OPT_TABLE['cp']
  380.     fu_output_message "cp#{options[:preserve] ? ' -p' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
  381.     return if options[:noop]
  382.     fu_each_src_dest(src, dest) do |s, d|
  383.       copy_file s, d, options[:preserve]
  384.     end
  385.   end
  386.   module_function :cp
  387.  
  388.   alias copy cp
  389.   module_function :copy
  390.  
  391.   OPT_TABLE['cp']   =
  392.   OPT_TABLE['copy'] = [:preserve, :noop, :verbose]
  393.  
  394.   #
  395.   # Options: preserve noop verbose dereference_root remove_destination
  396.   # 
  397.   # Copies +src+ to +dest+. If +src+ is a directory, this method copies
  398.   # all its contents recursively. If +dest+ is a directory, copies
  399.   # +src+ to +dest/src+.
  400.   #
  401.   # +src+ can be a list of files.
  402.   # 
  403.   #   # Installing ruby library "mylib" under the site_ruby
  404.   #   FileUtils.rm_r site_ruby + '/mylib', :force
  405.   #   FileUtils.cp_r 'lib/', site_ruby + '/mylib'
  406.   # 
  407.   #   # Examples of copying several files to target directory.
  408.   #   FileUtils.cp_r %w(mail.rb field.rb debug/), site_ruby + '/tmail'
  409.   #   FileUtils.cp_r Dir.glob('*.rb'), '/home/aamine/lib/ruby', :noop => true, :verbose => true
  410.   #
  411.   #   # If you want to copy all contents of a directory instead of the
  412.   #   # directory itself, c.f. src/x -> dest/x, src/y -> dest/y,
  413.   #   # use following code.
  414.   #   FileUtils.cp_r 'src/.', 'dest'     # cp_r('src', 'dest') makes src/dest,
  415.   #                                      # but this doesn't.
  416.   # 
  417.   def cp_r(src, dest, options = {})
  418.     fu_check_options options, OPT_TABLE['cp_r']
  419.     fu_output_message "cp -r#{options[:preserve] ? 'p' : ''}#{options[:remove_destination] ? ' --remove-destination' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
  420.     return if options[:noop]
  421.     options[:dereference_root] = true unless options.key?(:dereference_root)
  422.     fu_each_src_dest(src, dest) do |s, d|
  423.       copy_entry s, d, options[:preserve], options[:dereference_root], options[:remove_destination]
  424.     end
  425.   end
  426.   module_function :cp_r
  427.  
  428.   OPT_TABLE['cp_r'] = [:preserve, :noop, :verbose,
  429.                        :dereference_root, :remove_destination]
  430.  
  431.   #
  432.   # Copies a file system entry +src+ to +dest+.
  433.   # If +src+ is a directory, this method copies its contents recursively.
  434.   # This method preserves file types, c.f. symlink, directory...
  435.   # (FIFO, device files and etc. are not supported yet)
  436.   #
  437.   # Both of +src+ and +dest+ must be a path name.
  438.   # +src+ must exist, +dest+ must not exist.
  439.   #
  440.   # If +preserve+ is true, this method preserves owner, group, permissions
  441.   # and modified time.
  442.   #
  443.   # If +dereference_root+ is true, this method dereference tree root.
  444.   #
  445.   # If +remove_destination+ is true, this method removes each destination file before copy.
  446.   #
  447.   def copy_entry(src, dest, preserve = false, dereference_root = false, remove_destination = false)
  448.     Entry_.new(src, nil, dereference_root).traverse do |ent|
  449.       destent = Entry_.new(dest, ent.rel, false)
  450.       File.unlink destent.path if remove_destination && File.file?(destent.path)
  451.       ent.copy destent.path
  452.       ent.copy_metadata destent.path if preserve
  453.     end
  454.   end
  455.   module_function :copy_entry
  456.  
  457.   #
  458.   # Copies file contents of +src+ to +dest+.
  459.   # Both of +src+ and +dest+ must be a path name.
  460.   #
  461.   def copy_file(src, dest, preserve = false, dereference = true)
  462.     ent = Entry_.new(src, nil, dereference)
  463.     ent.copy_file dest
  464.     ent.copy_metadata dest if preserve
  465.   end
  466.   module_function :copy_file
  467.  
  468.   #
  469.   # Copies stream +src+ to +dest+.
  470.   # +src+ must respond to #read(n) and
  471.   # +dest+ must respond to #write(str).
  472.   #
  473.   def copy_stream(src, dest)
  474.     fu_copy_stream0 src, dest, fu_stream_blksize(src, dest)
  475.   end
  476.   module_function :copy_stream
  477.  
  478.   #
  479.   # Options: force noop verbose
  480.   # 
  481.   # Moves file(s) +src+ to +dest+.  If +file+ and +dest+ exist on the different
  482.   # disk partition, the file is copied instead.
  483.   # 
  484.   #   FileUtils.mv 'badname.rb', 'goodname.rb'
  485.   #   FileUtils.mv 'stuff.rb', '/notexist/lib/ruby', :force => true  # no error
  486.   # 
  487.   #   FileUtils.mv %w(junk.txt dust.txt), '/home/aamine/.trash/'
  488.   #   FileUtils.mv Dir.glob('test*.rb'), 'test', :noop => true, :verbose => true
  489.   # 
  490.   def mv(src, dest, options = {})
  491.     fu_check_options options, OPT_TABLE['mv']
  492.     fu_output_message "mv#{options[:force] ? ' -f' : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
  493.     return if options[:noop]
  494.     fu_each_src_dest(src, dest) do |s, d|
  495.       destent = Entry_.new(d, nil, true)
  496.       begin
  497.         if destent.exist?
  498.           if destent.directory?
  499.             raise Errno::EEXIST, dest
  500.           else
  501.             destent.remove_file if rename_cannot_overwrite_file?
  502.           end
  503.         end
  504.         begin
  505.           File.rename s, d
  506.         rescue Errno::EXDEV
  507.           copy_entry s, d, true
  508.           if options[:secure]
  509.             remove_entry_secure s, options[:force]
  510.           else
  511.             remove_entry s, options[:force]
  512.           end
  513.         end
  514.       rescue SystemCallError
  515.         raise unless options[:force]
  516.       end
  517.     end
  518.   end
  519.   module_function :mv
  520.  
  521.   alias move mv
  522.   module_function :move
  523.  
  524.   OPT_TABLE['mv']   =
  525.   OPT_TABLE['move'] = [:force, :noop, :verbose, :secure]
  526.  
  527.   def rename_cannot_overwrite_file?   #:nodoc:
  528.     /djgpp|cygwin|mswin|mingw|bccwin|wince|emx/ =~ RUBY_PLATFORM
  529.   end
  530.   private_module_function :rename_cannot_overwrite_file?
  531.  
  532.   #
  533.   # Options: force noop verbose
  534.   # 
  535.   # Remove file(s) specified in +list+.  This method cannot remove directories.
  536.   # All StandardErrors are ignored when the :force option is set.
  537.   # 
  538.   #   FileUtils.rm %w( junk.txt dust.txt )
  539.   #   FileUtils.rm Dir.glob('*.so')
  540.   #   FileUtils.rm 'NotExistFile', :force => true   # never raises exception
  541.   # 
  542.   def rm(list, options = {})
  543.     fu_check_options options, OPT_TABLE['rm']
  544.     list = fu_list(list)
  545.     fu_output_message "rm#{options[:force] ? ' -f' : ''} #{list.join ' '}" if options[:verbose]
  546.     return if options[:noop]
  547.  
  548.     list.each do |path|
  549.       remove_file path, options[:force]
  550.     end
  551.   end
  552.   module_function :rm
  553.  
  554.   alias remove rm
  555.   module_function :remove
  556.  
  557.   OPT_TABLE['rm']     =
  558.   OPT_TABLE['remove'] = [:force, :noop, :verbose]
  559.  
  560.   #
  561.   # Options: noop verbose
  562.   # 
  563.   # Equivalent to
  564.   #
  565.   #   #rm(list, :force => true)
  566.   #
  567.   def rm_f(list, options = {})
  568.     fu_check_options options, OPT_TABLE['rm_f']
  569.     options = options.dup
  570.     options[:force] = true
  571.     rm list, options
  572.   end
  573.   module_function :rm_f
  574.  
  575.   alias safe_unlink rm_f
  576.   module_function :safe_unlink
  577.  
  578.   OPT_TABLE['rm_f']        =
  579.   OPT_TABLE['safe_unlink'] = [:noop, :verbose]
  580.  
  581.   #
  582.   # Options: force noop verbose secure
  583.   # 
  584.   # remove files +list+[0] +list+[1]... If +list+[n] is a directory,
  585.   # removes its all contents recursively. This method ignores
  586.   # StandardError when :force option is set.
  587.   # 
  588.   #   FileUtils.rm_r Dir.glob('/tmp/*')
  589.   #   FileUtils.rm_r '/', :force => true          #  :-)
  590.   #
  591.   # WARNING: This method causes local vulnerability
  592.   # if one of parent directories or removing directory tree are world
  593.   # writable (including /tmp, whose permission is 1777), and the current
  594.   # process has strong privilege such as Unix super user (root), and the
  595.   # system has symbolic link.  For secure removing, read the documentation
  596.   # of #remove_entry_secure carefully, and set :secure option to true.
  597.   # Default is :secure=>false.
  598.   #
  599.   # NOTE: This method calls #remove_entry_secure if :secure option is set.
  600.   # See also #remove_entry_secure.
  601.   # 
  602.   def rm_r(list, options = {})
  603.     fu_check_options options, OPT_TABLE['rm_r']
  604.     # options[:secure] = true unless options.key?(:secure)
  605.     list = fu_list(list)
  606.     fu_output_message "rm -r#{options[:force] ? 'f' : ''} #{list.join ' '}" if options[:verbose]
  607.     return if options[:noop]
  608.     list.each do |path|
  609.       if options[:secure]
  610.         remove_entry_secure path, options[:force]
  611.       else
  612.         remove_entry path, options[:force]
  613.       end
  614.     end
  615.   end
  616.   module_function :rm_r
  617.  
  618.   OPT_TABLE['rm_r'] = [:force, :noop, :verbose, :secure]
  619.  
  620.   #
  621.   # Options: noop verbose secure
  622.   # 
  623.   # Equivalent to
  624.   #
  625.   #   #rm_r(list, :force => true)
  626.   #
  627.   # WARNING: This method causes local vulnerability.
  628.   # Read the documentation of #rm_r first.
  629.   # 
  630.   def rm_rf(list, options = {})
  631.     fu_check_options options, OPT_TABLE['rm_rf']
  632.     options = options.dup
  633.     options[:force] = true
  634.     rm_r list, options
  635.   end
  636.   module_function :rm_rf
  637.  
  638.   alias rmtree rm_rf
  639.   module_function :rmtree
  640.  
  641.   OPT_TABLE['rm_rf']  =
  642.   OPT_TABLE['rmtree'] = [:noop, :verbose, :secure]
  643.  
  644.   #
  645.   # This method removes a file system entry +path+.  +path+ shall be a
  646.   # regular file, a directory, or something.  If +path+ is a directory,
  647.   # remove it recursively.  This method is required to avoid TOCTTOU
  648.   # (time-of-check-to-time-of-use) local security vulnerability of #rm_r.
  649.   # #rm_r causes security hole when:
  650.   #
  651.   #   * Parent directory is world writable (including /tmp).
  652.   #   * Removing directory tree includes world writable directory.
  653.   #   * The system has symbolic link.
  654.   #
  655.   # To avoid this security hole, this method applies special preprocess.
  656.   # If +path+ is a directory, this method chown(2) and chmod(2) all
  657.   # removing directories.  This requires the current process is the
  658.   # owner of the removing whole directory tree, or is the super user (root).
  659.   #
  660.   # WARNING: You must ensure that *ALL* parent directories are not
  661.   # world writable.  Otherwise this method does not work.
  662.   # Only exception is temporary directory like /tmp and /var/tmp,
  663.   # whose permission is 1777.
  664.   #
  665.   # WARNING: Only the owner of the removing directory tree, or Unix super
  666.   # user (root) should invoke this method.  Otherwise this method does not
  667.   # work.
  668.   #
  669.   # For details of this security vulnerability, see Perl's case:
  670.   #
  671.   #   http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2005-0448
  672.   #   http://www.cve.mitre.org/cgi-bin/cvename.cgi?name=CAN-2004-0452
  673.   #
  674.   # For fileutils.rb, this vulnerability is reported in [ruby-dev:26100].
  675.   #
  676.   def remove_entry_secure(path, force = false)
  677.     unless fu_have_symlink?
  678.       remove_entry path, force
  679.       return
  680.     end
  681.     fullpath = File.expand_path(path)
  682.     st = File.lstat(fullpath)
  683.     unless st.directory?
  684.       File.unlink fullpath
  685.       return
  686.     end
  687.     # is a directory.
  688.     parent_st = File.stat(File.dirname(fullpath))
  689.     unless fu_world_writable?(parent_st)
  690.       remove_entry path, force
  691.       return
  692.     end
  693.     unless parent_st.sticky?
  694.       raise ArgumentError, "parent directory is world writable, FileUtils#remove_entry_secure does not work; abort: #{path.inspect} (parent directory mode #{'%o' % parent_st.mode})"
  695.     end
  696.     # freeze tree root
  697.     euid = Process.euid
  698.     File.open(fullpath + '/.') {|f|
  699.       unless fu_stat_identical_entry?(st, f.stat)
  700.         # symlink (TOC-to-TOU attack?)
  701.         File.unlink fullpath
  702.         return
  703.       end
  704.       f.chown euid, -1
  705.       f.chmod 0700
  706.     }
  707.     # ---- tree root is frozen ----
  708.     root = Entry_.new(path)
  709.     root.preorder_traverse do |ent|
  710.       if ent.directory?
  711.         ent.chown euid, -1
  712.         ent.chmod 0700
  713.       end
  714.     end
  715.     root.postorder_traverse do |ent|
  716.       begin
  717.         ent.remove
  718.       rescue
  719.         raise unless force
  720.       end
  721.     end
  722.   rescue
  723.     raise unless force
  724.   end
  725.   module_function :remove_entry_secure
  726.  
  727.   def fu_world_writable?(st)
  728.     (st.mode & 0002) != 0
  729.   end
  730.   private_module_function :fu_world_writable?
  731.  
  732.   def fu_have_symlink?   #:nodoc
  733.     File.symlink nil, nil
  734.   rescue NotImplementedError
  735.     return false
  736.   rescue
  737.     return true
  738.   end
  739.   private_module_function :fu_have_symlink?
  740.  
  741.   def fu_stat_identical_entry?(a, b)   #:nodoc:
  742.     a.dev == b.dev and a.ino == b.ino
  743.   end
  744.   private_module_function :fu_stat_identical_entry?
  745.  
  746.   #
  747.   # This method removes a file system entry +path+.
  748.   # +path+ might be a regular file, a directory, or something.
  749.   # If +path+ is a directory, remove it recursively.
  750.   #
  751.   # See also #remove_entry_secure.
  752.   #
  753.   def remove_entry(path, force = false)
  754.     Entry_.new(path).postorder_traverse do |ent|
  755.       begin
  756.         ent.remove
  757.       rescue
  758.         raise unless force
  759.       end
  760.     end
  761.   rescue
  762.     raise unless force
  763.   end
  764.   module_function :remove_entry
  765.  
  766.   #
  767.   # Removes a file +path+.
  768.   # This method ignores StandardError if +force+ is true.
  769.   #
  770.   def remove_file(path, force = false)
  771.     Entry_.new(path).remove_file
  772.   rescue
  773.     raise unless force
  774.   end
  775.   module_function :remove_file
  776.  
  777.   #
  778.   # Removes a directory +dir+ and its contents recursively.
  779.   # This method ignores StandardError if +force+ is true.
  780.   #
  781.   def remove_dir(path, force = false)
  782.     remove_entry path, force   # FIXME?? check if it is a directory
  783.   end
  784.   module_function :remove_dir
  785.  
  786.   #
  787.   # Returns true if the contents of a file A and a file B are identical.
  788.   # 
  789.   #   FileUtils.compare_file('somefile', 'somefile')  #=> true
  790.   #   FileUtils.compare_file('/bin/cp', '/bin/mv')    #=> maybe false
  791.   #
  792.   def compare_file(a, b)
  793.     return false unless File.size(a) == File.size(b)
  794.     File.open(a, 'rb') {|fa|
  795.       File.open(b, 'rb') {|fb|
  796.         return compare_stream(fa, fb)
  797.       }
  798.     }
  799.   end
  800.   module_function :compare_file
  801.  
  802.   alias identical? compare_file
  803.   alias cmp compare_file
  804.   module_function :identical?
  805.   module_function :cmp
  806.  
  807.   #
  808.   # Returns true if the contents of a stream +a+ and +b+ are identical.
  809.   #
  810.   def compare_stream(a, b)
  811.     bsize = fu_stream_blksize(a, b)
  812.     sa = sb = nil
  813.     while sa == sb
  814.       sa = a.read(bsize)
  815.       sb = b.read(bsize)
  816.       unless sa and sb
  817.         if sa.nil? and sb.nil?
  818.           return true
  819.         end
  820.       end
  821.     end
  822.     false
  823.   end
  824.   module_function :compare_stream
  825.  
  826.   #
  827.   # Options: mode preserve noop verbose
  828.   # 
  829.   # If +src+ is not same as +dest+, copies it and changes the permission
  830.   # mode to +mode+.  If +dest+ is a directory, destination is +dest+/+src+.
  831.   # This method removes destination before copy.
  832.   # 
  833.   #   FileUtils.install 'ruby', '/usr/local/bin/ruby', :mode => 0755, :verbose => true
  834.   #   FileUtils.install 'lib.rb', '/usr/local/lib/ruby/site_ruby', :verbose => true
  835.   # 
  836.   def install(src, dest, options = {})
  837.     fu_check_options options, OPT_TABLE['install']
  838.     fu_output_message "install -c#{options[:preserve] && ' -p'}#{options[:mode] ? (' -m 0%o' % options[:mode]) : ''} #{[src,dest].flatten.join ' '}" if options[:verbose]
  839.     return if options[:noop]
  840.     fu_each_src_dest(src, dest) do |s, d|
  841.       unless File.exist?(d) and compare_file(s, d)
  842.         remove_file d, true
  843.         st = File.stat(s) if options[:preserve]
  844.         copy_file s, d
  845.         File.utime st.atime, st.mtime, d if options[:preserve]
  846.         File.chmod options[:mode], d if options[:mode]
  847.       end
  848.     end
  849.   end
  850.   module_function :install
  851.  
  852.   OPT_TABLE['install'] = [:mode, :preserve, :noop, :verbose]
  853.  
  854.   #
  855.   # Options: noop verbose
  856.   # 
  857.   # Changes permission bits on the named files (in +list+) to the bit pattern
  858.   # represented by +mode+.
  859.   # 
  860.   #   FileUtils.chmod 0755, 'somecommand'
  861.   #   FileUtils.chmod 0644, %w(my.rb your.rb his.rb her.rb)
  862.   #   FileUtils.chmod 0755, '/usr/bin/ruby', :verbose => true
  863.   # 
  864.   def chmod(mode, list, options = {})
  865.     fu_check_options options, OPT_TABLE['chmod']
  866.     list = fu_list(list)
  867.     fu_output_message sprintf('chmod %o %s', mode, list.join(' ')) if options[:verbose]
  868.     return if options[:noop]
  869.     list.each do |path|
  870.       Entry_.new(path).chmod mode
  871.     end
  872.   end
  873.   module_function :chmod
  874.  
  875.   OPT_TABLE['chmod'] = [:noop, :verbose]
  876.  
  877.   #
  878.   # Options: noop verbose force
  879.   # 
  880.   # Changes permission bits on the named files (in +list+)
  881.   # to the bit pattern represented by +mode+.
  882.   # 
  883.   #   FileUtils.chmod_R 0700, "/tmp/app.#{$$}"
  884.   # 
  885.   def chmod_R(mode, list, options = {})
  886.     fu_check_options options, OPT_TABLE['chmod_R']
  887.     list = fu_list(list)
  888.     fu_output_message sprintf('chmod -R%s %o %s',
  889.                               (options[:force] ? 'f' : ''),
  890.                               mode, list.join(' ')) if options[:verbose]
  891.     return if options[:noop]
  892.     list.each do |root|
  893.       Entry_.new(root).traverse do |ent|
  894.         begin
  895.           ent.chmod mode
  896.         rescue
  897.           raise unless options[:force]
  898.         end
  899.       end
  900.     end
  901.   end
  902.   module_function :chmod_R
  903.  
  904.   OPT_TABLE['chmod_R'] = [:noop, :verbose, :force]
  905.  
  906.   #
  907.   # Options: noop verbose
  908.   # 
  909.   # Changes owner and group on the named files (in +list+)
  910.   # to the user +user+ and the group +group+.  +user+ and +group+
  911.   # may be an ID (Integer/String) or a name (String).
  912.   # If +user+ or +group+ is nil, this method does not change
  913.   # the attribute.
  914.   # 
  915.   #   FileUtils.chown 'root', 'staff', '/usr/local/bin/ruby'
  916.   #   FileUtils.chown nil, 'bin', Dir.glob('/usr/bin/*'), :verbose => true
  917.   # 
  918.   def chown(user, group, list, options = {})
  919.     fu_check_options options, OPT_TABLE['chown']
  920.     list = fu_list(list)
  921.     fu_output_message sprintf('chown %s%s',
  922.                               [user,group].compact.join(':') + ' ',
  923.                               list.join(' ')) if options[:verbose]
  924.     return if options[:noop]
  925.     uid = fu_get_uid(user)
  926.     gid = fu_get_gid(group)
  927.     list.each do |path|
  928.       Entry_.new(path).chown uid, gid
  929.     end
  930.   end
  931.   module_function :chown
  932.  
  933.   OPT_TABLE['chown'] = [:noop, :verbose]
  934.  
  935.   #
  936.   # Options: noop verbose force
  937.   # 
  938.   # Changes owner and group on the named files (in +list+)
  939.   # to the user +user+ and the group +group+ recursively.
  940.   # +user+ and +group+ may be an ID (Integer/String) or
  941.   # a name (String).  If +user+ or +group+ is nil, this
  942.   # method does not change the attribute.
  943.   # 
  944.   #   FileUtils.chown_R 'www', 'www', '/var/www/htdocs'
  945.   #   FileUtils.chown_R 'cvs', 'cvs', '/var/cvs', :verbose => true
  946.   # 
  947.   def chown_R(user, group, list, options = {})
  948.     fu_check_options options, OPT_TABLE['chown_R']
  949.     list = fu_list(list)
  950.     fu_output_message sprintf('chown -R%s %s%s',
  951.                               (options[:force] ? 'f' : ''),
  952.                               [user,group].compact.join(':') + ' ',
  953.                               list.join(' ')) if options[:verbose]
  954.     return if options[:noop]
  955.     uid = fu_get_uid(user)
  956.     gid = fu_get_gid(group)
  957.     return unless uid or gid
  958.     list.each do |root|
  959.       Entry_.new(root).traverse do |ent|
  960.         begin
  961.           ent.chown uid, gid
  962.         rescue
  963.           raise unless options[:force]
  964.         end
  965.       end
  966.     end
  967.   end
  968.   module_function :chown_R
  969.  
  970.   OPT_TABLE['chown_R'] = [:noop, :verbose, :force]
  971.  
  972.   begin
  973.     require 'etc'
  974.  
  975.     def fu_get_uid(user)   #:nodoc:
  976.       return nil unless user
  977.       user = user.to_s
  978.       if /\A\d+\z/ =~ user
  979.       then user.to_i
  980.       else Etc.getpwnam(user).uid
  981.       end
  982.     end
  983.     private_module_function :fu_get_uid
  984.  
  985.     def fu_get_gid(group)   #:nodoc:
  986.       return nil unless group
  987.       if /\A\d+\z/ =~ group
  988.       then group.to_i
  989.       else Etc.getgrnam(group).gid
  990.       end
  991.     end
  992.     private_module_function :fu_get_gid
  993.  
  994.   rescue LoadError
  995.     # need Win32 support???
  996.  
  997.     def fu_get_uid(user)   #:nodoc:
  998.       user    # FIXME
  999.     end
  1000.     private_module_function :fu_get_uid
  1001.  
  1002.     def fu_get_gid(group)   #:nodoc:
  1003.       group   # FIXME
  1004.     end
  1005.     private_module_function :fu_get_gid
  1006.   end
  1007.  
  1008.   #
  1009.   # Options: noop verbose
  1010.   # 
  1011.   # Updates modification time (mtime) and access time (atime) of file(s) in
  1012.   # +list+.  Files are created if they don't exist.
  1013.   # 
  1014.   #   FileUtils.touch 'timestamp'
  1015.   #   FileUtils.touch Dir.glob('*.c');  system 'make'
  1016.   # 
  1017.   def touch(list, options = {})
  1018.     fu_check_options options, OPT_TABLE['touch']
  1019.     list = fu_list(list)
  1020.     created = nocreate = options[:nocreate]
  1021.     t = options[:mtime]
  1022.     if options[:verbose]
  1023.       fu_output_message "touch #{nocreate ? ' -c' : ''}#{t ? t.strftime(' -t %Y%m%d%H%M.%S') : ''}#{list.join ' '}"
  1024.     end
  1025.     return if options[:noop]
  1026.     list.each do |path|
  1027.       created = nocreate
  1028.       begin
  1029.         File.utime(t, t, path)
  1030.       rescue Errno::ENOENT
  1031.         raise if created
  1032.         File.open(path, 'a') {
  1033.           ;
  1034.         }
  1035.         created = true
  1036.         retry if t
  1037.       end
  1038.     end
  1039.   end
  1040.   module_function :touch
  1041.  
  1042.   OPT_TABLE['touch'] = [:noop, :verbose, :mtime, :nocreate]
  1043.  
  1044.   private
  1045.  
  1046.   module StreamUtils_
  1047.     private
  1048.  
  1049.     def fu_windows?
  1050.       /mswin|mingw|bccwin|wince|emx/ =~ RUBY_PLATFORM
  1051.     end
  1052.  
  1053.     def fu_copy_stream0(src, dest, blksize)   #:nodoc:
  1054.       # FIXME: readpartial?
  1055.       while s = src.read(blksize)
  1056.         dest.write s
  1057.       end
  1058.     end
  1059.  
  1060.     def fu_stream_blksize(*streams)
  1061.       streams.each do |s|
  1062.         next unless s.respond_to?(:stat)
  1063.         size = fu_blksize(s.stat)
  1064.         return size if size
  1065.       end
  1066.       fu_default_blksize()
  1067.     end
  1068.  
  1069.     def fu_blksize(st)
  1070.       s = st.blksize
  1071.       return nil unless s
  1072.       return nil if s == 0
  1073.       s
  1074.     end
  1075.  
  1076.     def fu_default_blksize
  1077.       1024
  1078.     end
  1079.   end
  1080.  
  1081.   include StreamUtils_
  1082.   extend StreamUtils_
  1083.  
  1084.   class Entry_   #:nodoc: internal use only
  1085.     include StreamUtils_
  1086.  
  1087.     def initialize(a, b = nil, deref = false)
  1088.       @prefix = @rel = @path = nil
  1089.       if b
  1090.         @prefix = a
  1091.         @rel = b
  1092.       else
  1093.         @path = a
  1094.       end
  1095.       @deref = deref
  1096.       @stat = nil
  1097.       @lstat = nil
  1098.     end
  1099.  
  1100.     def inspect
  1101.       "\#<#{self.class} #{path()}>"
  1102.     end
  1103.  
  1104.     def path
  1105.       if @path
  1106.         @path.to_str
  1107.       else
  1108.         join(@prefix, @rel)
  1109.       end
  1110.     end
  1111.  
  1112.     def prefix
  1113.       @prefix || @path
  1114.     end
  1115.  
  1116.     def rel
  1117.       @rel
  1118.     end
  1119.  
  1120.     def dereference?
  1121.       @deref
  1122.     end
  1123.  
  1124.     def exist?
  1125.       lstat! ? true : false
  1126.     end
  1127.  
  1128.     def file?
  1129.       s = lstat!
  1130.       s and s.file?
  1131.     end
  1132.  
  1133.     def directory?
  1134.       s = lstat!
  1135.       s and s.directory?
  1136.     end
  1137.  
  1138.     def symlink?
  1139.       s = lstat!
  1140.       s and s.symlink?
  1141.     end
  1142.  
  1143.     def chardev?
  1144.       s = lstat!
  1145.       s and s.chardev?
  1146.     end
  1147.  
  1148.     def blockdev?
  1149.       s = lstat!
  1150.       s and s.blockdev?
  1151.     end
  1152.  
  1153.     def socket?
  1154.       s = lstat!
  1155.       s and s.socket?
  1156.     end
  1157.  
  1158.     def pipe?
  1159.       s = lstat!
  1160.       s and s.pipe?
  1161.     end
  1162.  
  1163.     S_IF_DOOR = 0xD000
  1164.  
  1165.     def door?
  1166.       s = lstat!
  1167.       s and (s.mode & 0xF000 == S_IF_DOOR)
  1168.     end
  1169.  
  1170.     def entries
  1171.       Dir.entries(path())\
  1172.           .reject {|n| n == '.' or n == '..' }\
  1173.           .map {|n| Entry_.new(prefix(), join(rel(), n.untaint)) }
  1174.     end
  1175.  
  1176.     def stat
  1177.       return @stat if @stat
  1178.       if lstat() and lstat().symlink?
  1179.         @stat = File.stat(path())
  1180.       else
  1181.         @stat = lstat()
  1182.       end
  1183.       @stat
  1184.     end
  1185.  
  1186.     def stat!
  1187.       return @stat if @stat
  1188.       if lstat! and lstat!.symlink?
  1189.         @stat = File.stat(path())
  1190.       else
  1191.         @stat = lstat!
  1192.       end
  1193.       @stat
  1194.     rescue SystemCallError
  1195.       nil
  1196.     end
  1197.  
  1198.     def lstat
  1199.       if dereference?
  1200.         @lstat ||= File.stat(path())
  1201.       else
  1202.         @lstat ||= File.lstat(path())
  1203.       end
  1204.     end
  1205.  
  1206.     def lstat!
  1207.       lstat()
  1208.     rescue SystemCallError
  1209.       nil
  1210.     end
  1211.  
  1212.     def chmod(mode)
  1213.       if symlink?
  1214.         File.lchmod mode, path() if have_lchmod?
  1215.       else
  1216.         File.chmod mode, path()
  1217.       end
  1218.     end
  1219.  
  1220.     def chown(uid, gid)
  1221.       if symlink?
  1222.         File.lchown uid, gid, path() if have_lchown?
  1223.       else
  1224.         File.chown uid, gid, path()
  1225.       end
  1226.     end
  1227.  
  1228.     def copy(dest)
  1229.       case
  1230.       when file?
  1231.         copy_file dest
  1232.       when directory?
  1233.         begin
  1234.           Dir.mkdir dest
  1235.         rescue
  1236.           raise unless File.directory?(dest)
  1237.         end
  1238.       when symlink?
  1239.         File.symlink File.readlink(path()), dest
  1240.       when chardev?
  1241.         raise "cannot handle device file" unless File.respond_to?(:mknod)
  1242.         mknod dest, ?c, 0666, lstat().rdev
  1243.       when blockdev?
  1244.         raise "cannot handle device file" unless File.respond_to?(:mknod)
  1245.         mknod dest, ?b, 0666, lstat().rdev
  1246.       when socket?
  1247.         raise "cannot handle socket" unless File.respond_to?(:mknod)
  1248.         mknod dest, nil, lstat().mode, 0
  1249.       when pipe?
  1250.         raise "cannot handle FIFO" unless File.respond_to?(:mkfifo)
  1251.         mkfifo dest, 0666
  1252.       when door?
  1253.         raise "cannot handle door: #{path()}"
  1254.       else
  1255.         raise "unknown file type: #{path()}"
  1256.       end
  1257.     end
  1258.  
  1259.     def copy_file(dest)
  1260.       st = stat()
  1261.       File.open(path(),  'rb') {|r|
  1262.         File.open(dest, 'wb', st.mode) {|w|
  1263.           fu_copy_stream0 r, w, (fu_blksize(st) || fu_default_blksize())
  1264.         }
  1265.       }
  1266.     end
  1267.  
  1268.     def copy_metadata(path)
  1269.       st = lstat()
  1270.       File.utime st.atime, st.mtime, path
  1271.       begin
  1272.         File.chown st.uid, st.gid, path
  1273.       rescue Errno::EPERM
  1274.         # clear setuid/setgid
  1275.         File.chmod st.mode & 01777, path
  1276.       else
  1277.         File.chmod st.mode, path
  1278.       end
  1279.     end
  1280.  
  1281.     def remove
  1282.       if directory?
  1283.         remove_dir1
  1284.       else
  1285.         remove_file
  1286.       end
  1287.     end
  1288.  
  1289.     def remove_dir1
  1290.       platform_support {
  1291.         Dir.rmdir path().sub(%r</\z>, '')
  1292.       }
  1293.     end
  1294.  
  1295.     def remove_file
  1296.       platform_support {
  1297.         File.unlink path
  1298.       }
  1299.     end
  1300.  
  1301.     def platform_support
  1302.       return yield unless fu_windows?
  1303.       first_time_p = true
  1304.       begin
  1305.         yield
  1306.       rescue Errno::ENOENT
  1307.         raise
  1308.       rescue => err
  1309.         if first_time_p
  1310.           first_time_p = false
  1311.           begin
  1312.             File.chmod 0700, path()   # Windows does not have symlink
  1313.             retry
  1314.           rescue SystemCallError
  1315.           end
  1316.         end
  1317.         raise err
  1318.       end
  1319.     end
  1320.  
  1321.     def preorder_traverse
  1322.       stack = [self]
  1323.       while ent = stack.pop
  1324.         yield ent
  1325.         stack.concat ent.entries.reverse if ent.directory?
  1326.       end
  1327.     end
  1328.  
  1329.     alias traverse preorder_traverse
  1330.  
  1331.     def postorder_traverse
  1332.       if directory?
  1333.         entries().each do |ent|
  1334.           ent.postorder_traverse do |e|
  1335.             yield e
  1336.           end
  1337.         end
  1338.       end
  1339.       yield self
  1340.     end
  1341.  
  1342.     private
  1343.  
  1344.     $fileutils_rb_have_lchmod = nil
  1345.  
  1346.     def have_lchmod?
  1347.       # This is not MT-safe, but it does not matter.
  1348.       if $fileutils_rb_have_lchmod == nil
  1349.         $fileutils_rb_have_lchmod = check_have_lchmod?
  1350.       end
  1351.       $fileutils_rb_have_lchmod
  1352.     end
  1353.  
  1354.     def check_have_lchmod?
  1355.       return false unless File.respond_to?(:lchmod)
  1356.       File.lchmod 0
  1357.       return true
  1358.     rescue NotImplementedError
  1359.       return false
  1360.     end
  1361.  
  1362.     $fileutils_rb_have_lchown = nil
  1363.  
  1364.     def have_lchown?
  1365.       # This is not MT-safe, but it does not matter.
  1366.       if $fileutils_rb_have_lchown == nil
  1367.         $fileutils_rb_have_lchown = check_have_lchown?
  1368.       end
  1369.       $fileutils_rb_have_lchown
  1370.     end
  1371.  
  1372.     def check_have_lchown?
  1373.       return false unless File.respond_to?(:lchown)
  1374.       File.lchown nil, nil
  1375.       return true
  1376.     rescue NotImplementedError
  1377.       return false
  1378.     end
  1379.  
  1380.     def join(dir, base)
  1381.       return dir.to_str if not base or base == '.'
  1382.       return base.to_str if not dir or dir == '.'
  1383.       File.join(dir, base)
  1384.     end
  1385.   end   # class Entry_
  1386.  
  1387.   def fu_list(arg)   #:nodoc:
  1388.     [arg].flatten.map {|path| path.to_str }
  1389.   end
  1390.   private_module_function :fu_list
  1391.  
  1392.   def fu_each_src_dest(src, dest)   #:nodoc:
  1393.     fu_each_src_dest0(src, dest) do |s, d|
  1394.       raise ArgumentError, "same file: #{s} and #{d}" if fu_same?(s, d)
  1395.       yield s, d
  1396.     end
  1397.   end
  1398.   private_module_function :fu_each_src_dest
  1399.  
  1400.   def fu_each_src_dest0(src, dest)   #:nodoc:
  1401.     if src.is_a?(Array)
  1402.       src.each do |s|
  1403.         s = s.to_str
  1404.         yield s, File.join(dest, File.basename(s))
  1405.       end
  1406.     else
  1407.       src = src.to_str
  1408.       if File.directory?(dest)
  1409.         yield src, File.join(dest, File.basename(src))
  1410.       else
  1411.         yield src, dest.to_str
  1412.       end
  1413.     end
  1414.   end
  1415.   private_module_function :fu_each_src_dest0
  1416.  
  1417.   def fu_same?(a, b)   #:nodoc:
  1418.     if fu_have_st_ino?
  1419.       st1 = File.stat(a)
  1420.       st2 = File.stat(b)
  1421.       st1.dev == st2.dev and st1.ino == st2.ino
  1422.     else
  1423.       File.expand_path(a) == File.expand_path(b)
  1424.     end
  1425.   rescue Errno::ENOENT
  1426.     return false
  1427.   end
  1428.   private_module_function :fu_same?
  1429.  
  1430.   def fu_have_st_ino?   #:nodoc:
  1431.     not fu_windows?
  1432.   end
  1433.   private_module_function :fu_have_st_ino?
  1434.  
  1435.   def fu_check_options(options, optdecl)   #:nodoc:
  1436.     h = options.dup
  1437.     optdecl.each do |opt|
  1438.       h.delete opt
  1439.     end
  1440.     raise ArgumentError, "no such option: #{h.keys.join(' ')}" unless h.empty?
  1441.   end
  1442.   private_module_function :fu_check_options
  1443.  
  1444.   def fu_update_option(args, new)   #:nodoc:
  1445.     if args.last.is_a?(Hash)
  1446.       args[-1] = args.last.dup.update(new)
  1447.     else
  1448.       args.push new
  1449.     end
  1450.     args
  1451.   end
  1452.   private_module_function :fu_update_option
  1453.  
  1454.   @fileutils_output = $stderr
  1455.   @fileutils_label  = ''
  1456.  
  1457.   def fu_output_message(msg)   #:nodoc:
  1458.     @fileutils_output ||= $stderr
  1459.     @fileutils_label  ||= ''
  1460.     @fileutils_output.puts @fileutils_label + msg
  1461.   end
  1462.   private_module_function :fu_output_message
  1463.  
  1464.   #
  1465.   # Returns an Array of method names which have any options.
  1466.   #
  1467.   #   p FileUtils.commands  #=> ["chmod", "cp", "cp_r", "install", ...]
  1468.   #
  1469.   def FileUtils.commands
  1470.     OPT_TABLE.keys
  1471.   end
  1472.  
  1473.   #
  1474.   # Returns an Array of option names.
  1475.   #
  1476.   #   p FileUtils.options  #=> ["noop", "force", "verbose", "preserve", "mode"]
  1477.   #
  1478.   def FileUtils.options
  1479.     OPT_TABLE.values.flatten.uniq.map {|sym| sym.to_s }
  1480.   end
  1481.  
  1482.   #
  1483.   # Returns true if the method +mid+ have an option +opt+.
  1484.   #
  1485.   #   p FileUtils.have_option?(:cp, :noop)     #=> true
  1486.   #   p FileUtils.have_option?(:rm, :force)    #=> true
  1487.   #   p FileUtils.have_option?(:rm, :perserve) #=> false
  1488.   #
  1489.   def FileUtils.have_option?(mid, opt)
  1490.     li = OPT_TABLE[mid.to_s] or raise ArgumentError, "no such method: #{mid}"
  1491.     li.include?(opt)
  1492.   end
  1493.  
  1494.   #
  1495.   # Returns an Array of option names of the method +mid+.
  1496.   #
  1497.   #   p FileUtils.options(:rm)  #=> ["noop", "verbose", "force"]
  1498.   #
  1499.   def FileUtils.options_of(mid)
  1500.     OPT_TABLE[mid.to_s].map {|sym| sym.to_s }
  1501.   end
  1502.  
  1503.   #
  1504.   # Returns an Array of method names which have the option +opt+.
  1505.   #
  1506.   #   p FileUtils.collect_method(:preserve) #=> ["cp", "cp_r", "copy", "install"]
  1507.   #
  1508.   def FileUtils.collect_method(opt)
  1509.     OPT_TABLE.keys.select {|m| OPT_TABLE[m].include?(opt) }
  1510.   end
  1511.  
  1512.   METHODS = singleton_methods() - %w( private_module_function
  1513.       commands options have_option? options_of collect_method )
  1514.  
  1515.   # 
  1516.   # This module has all methods of FileUtils module, but it outputs messages
  1517.   # before acting.  This equates to passing the <tt>:verbose</tt> flag to
  1518.   # methods in FileUtils.
  1519.   # 
  1520.   module Verbose
  1521.     include FileUtils
  1522.     @fileutils_output  = $stderr
  1523.     @fileutils_label   = ''
  1524.     ::FileUtils.collect_method(:verbose).each do |name|
  1525.       module_eval(<<-EOS, __FILE__, __LINE__ + 1)
  1526.         def #{name}(*args)
  1527.           super(*fu_update_option(args, :verbose => true))
  1528.         end
  1529.         private :#{name}
  1530.       EOS
  1531.     end
  1532.     extend self
  1533.     class << self
  1534.       ::FileUtils::METHODS.each do |m|
  1535.         public m
  1536.       end
  1537.     end
  1538.   end
  1539.  
  1540.   # 
  1541.   # This module has all methods of FileUtils module, but never changes
  1542.   # files/directories.  This equates to passing the <tt>:noop</tt> flag
  1543.   # to methods in FileUtils.
  1544.   # 
  1545.   module NoWrite
  1546.     include FileUtils
  1547.     @fileutils_output  = $stderr
  1548.     @fileutils_label   = ''
  1549.     ::FileUtils.collect_method(:noop).each do |name|
  1550.       module_eval(<<-EOS, __FILE__, __LINE__ + 1)
  1551.         def #{name}(*args)
  1552.           super(*fu_update_option(args, :noop => true))
  1553.         end
  1554.         private :#{name}
  1555.       EOS
  1556.     end
  1557.     extend self
  1558.     class << self
  1559.       ::FileUtils::METHODS.each do |m|
  1560.         public m
  1561.       end
  1562.     end
  1563.   end
  1564.  
  1565.   # 
  1566.   # This module has all methods of FileUtils module, but never changes
  1567.   # files/directories, with printing message before acting.
  1568.   # This equates to passing the <tt>:noop</tt> and <tt>:verbose</tt> flag
  1569.   # to methods in FileUtils.
  1570.   # 
  1571.   module DryRun
  1572.     include FileUtils
  1573.     @fileutils_output  = $stderr
  1574.     @fileutils_label   = ''
  1575.     ::FileUtils.collect_method(:noop).each do |name|
  1576.       module_eval(<<-EOS, __FILE__, __LINE__ + 1)
  1577.         def #{name}(*args)
  1578.           super(*fu_update_option(args, :noop => true, :verbose => true))
  1579.         end
  1580.         private :#{name}
  1581.       EOS
  1582.     end
  1583.     extend self
  1584.     class << self
  1585.       ::FileUtils::METHODS.each do |m|
  1586.         public m
  1587.       end
  1588.     end
  1589.   end
  1590.  
  1591. end
  1592.